Los agentes de IA en el desarrollo de software llevan tiempo prometiendo más de lo que dan. Ahora empieza a tomar forma una idea diferente: usar el modelo más potente para entender el repositorio y escribir planes de mejora, pero no para tocar el código directamente. shadcn/improve aparece como una skill de agente con esa lógica: separa quién piensa de quién ejecuta, y convierte el plan en el producto final del modelo caro.
El enfoque responde a un problema que cada vez es más común en los equipos técnicos. Los modelos avanzados son buenos para entender bases de código complejas, detectar deuda técnica, priorizar riesgos y escribir especificaciones. Pero también son caros, y si se usan para cada cambio menor, cada refactorización o cada ajuste repetitivo, la factura puede crecer muy rápido. shadcn/improve intenta separar la inteligencia de la ejecución: el modelo caro piensa y planifica, y otro agente más barato ejecuta con instrucciones precisas.
El plan como producto, no el código generado
La filosofía de shadcn/improve cabe en una frase: el plan es el producto. La skill no toca el código fuente del proyecto. Su trabajo es inspeccionar el repositorio, identificar hallazgos, priorizarlos y generar planes de implementación autocontenidos en Markdown dentro de una carpeta plans/. Luego otro agente, o un desarrollador humano, puede ejecutar esos planes.
Esto cambia la forma de usar la IA en el desarrollo. En vez de delegar toda una tarea a un agente que improvisa sobre la marcha, el sistema obliga primero a documentar el problema, citar rutas de ficheros, incluir fragmentos del estado actual, definir pasos verificables, listar comandos de prueba y dejar explícitas las condiciones de parada. Es una forma de convertir el uso de IA en algo más parecido a cómo trabaja un tech lead: revisar, priorizar, especificar y ejecutar con control.
Comando | Uso principal |
| Auditoría completa del repositorio, hallazgos priorizados y planes |
| Revisión rápida y económica de los puntos más críticos |
| Auditoría exhaustiva por paquetes y categorías |
| Revisión centrada en seguridad |
| Auditoría limitada a los cambios de la rama actual |
| Sugerencias de evolución del proyecto basadas en evidencias |
| Crea un plan concreto sin auditoría previa |
| Critica y refina un plan existente |
| Delega la ejecución a un agente más barato y revisa el resultado |
| Actualiza el backlog de planes: verifica, desbloquea o retira items |
La instalación se presenta con un comando directo: npx skills add shadcn/improve. Funciona en agentes compatibles con el formato Agent Skills y genera los planes en texto plano, lo que hace que el resultado sea independiente de una sesión concreta con un modelo. Un plan puede leerlo otro agente, otro desarrollador o el equipo en una revisión interna.
Por qué separar auditoría y ejecución puede ahorrar dinero
El enfoque tiene sentido económico. En la programación asistida por IA, las partes más caras suelen ser las que requieren mayor comprensión: leer el repositorio, entender las convenciones, evaluar el impacto, detectar problemas reales y evitar falsos positivos. Ahí es donde un modelo de gama alta puede aportar más valor. Por el contrario, implementar una lista concreta de pasos, pasar tests, aplicar cambios mecánicos o corregir una duplicación localizada puede delegarse a un modelo más barato si el plan está bien escrito.
Lo clave es la calidad de la especificación. shadcn/improve escribe planes pensados para «el ejecutor plausible más débil», es decir, un agente que nunca vio la sesión con el advisor y que puede tener mucha menos capacidad de razonamiento. Por eso incluye contexto, rutas exactas, fragmentos de código, comandos de verificación, criterios de completitud y límites de alcance.
Fase | Modelo recomendado | Motivo |
Reconocimiento del repositorio | Modelo potente | Necesita entender arquitectura, stack y convenciones |
Auditoría de problemas | Modelo potente | Requiere juicio técnico y priorización |
Escritura de planes | Modelo potente | Debe producir instrucciones completas y verificables |
Implementación guiada | Modelo barato o humano | Sigue pasos definidos y acotados |
Ejecución de tests | Agente barato o entorno local | Trabajo mecánico con salida verificable |
Revisión final | Modelo potente o dev senior | Comprueba intención, alcance y calidad del diff |
Los ahorros no vienen solo de usar menos el modelo caro. También pueden venir de reducir las iteraciones fallidas. Muchos costes de desarrollo con IA aparecen cuando el agente cambia demasiado, rompe tests, se sale del alcance o inventa una solución porque no entendía el contexto. Si el plan incluye condiciones de parada, comandos esperados y límites de alcance, el ejecutor tiene menos margen para desviarse.
Auditorías con evidencias, no recomendaciones genéricas
La skill no busca producir listas genéricas de «buenas prácticas». Durante la auditoría lanza subagentes por categorías como corrección, seguridad, rendimiento, cobertura de tests, deuda técnica, dependencias, experiencia del desarrollador, documentación y dirección del producto. Cada hallazgo debe estar respaldado por evidencia del propio repositorio, con referencias a ficheros y líneas.
Después el advisor relee los puntos citados antes de mostrarlos. Esta segunda revisión busca reducir falsos positivos, corregir atribuciones erróneas y registrar los rechazos para que no reaparezcan en ejecuciones futuras. En el ejemplo que comparte el proyecto, una supuesta alerta de SSRF vinculada a una variable https_proxy se rechaza como comportamiento esperado porque sigue una convención estándar usada por muchas herramientas CLI.
Categoría de auditoría | Lo que puede detectar |
Corrección | Errores lógicos, casos límite o comportamiento inconsistente |
Seguridad | Riesgos reales respaldados por evidencia en el código |
Rendimiento | Algoritmos costosos, consultas ineficientes o trabajo duplicado |
Tests | Áreas críticas sin cobertura suficiente |
Deuda técnica | Duplicaciones, abstracciones rotas o migraciones incompletas |
Dependencias | Actualizaciones, incompatibilidades o paquetes problemáticos |
DX | Fricciones en el desarrollo, las pruebas o el despliegue |
Documentación | Instrucciones incompletas u obsoletas |
Dirección | Ideas de producto justificadas por el estado actual del repositorio |
Esta insistencia en la evidencia resulta útil porque uno de los grandes problemas de los agentes de código es el ruido. Un modelo puede detectar «problemas» que en realidad son decisiones deliberadas, deuda asumida o patrones propios del proyecto. Si cada hallazgo debe citar código concreto y pasar una revisión interna, el resultado se parece más a una auditoría técnica que a una lista de consejos genéricos.
Planes diseñados para sobrevivir fuera de la sesión
Los planes que genera shadcn/improve son autocontenidos. Incluyen el commit contra el que se escribieron, para que el ejecutor pueda comprobar si el código ha derivado antes de tocar nada. Si el código ha cambiado demasiado, el plan debe parar e informar del problema en vez de improvisar.
También incluyen «puertas de verificación». Cada paso termina con un comando y una salida esperada, lo que hace el éxito más medible. El agente no tiene que decidir si algo «parece hecho»; tiene que pasar tests, linting, compilación u otros criterios definidos por el propio repositorio.
Propiedad del plan | Valor para el equipo |
Contexto inline | El ejecutor no depende de la conversación original |
Rutas exactas | Reduce la exploración innecesaria |
Fragmentos de código | Aclara el estado actual antes del cambio |
Comandos verificados | Usa las herramientas reales del repositorio |
Criterios de completitud | Evita cierres ambiguos |
Condiciones de parada | Evita que un modelo pequeño improvise |
Commit de referencia | Detecta si el plan ha quedado desfasado |
Límites de alcance | Reduce los cambios colaterales no deseados |
Este enfoque puede encajar bien en equipos que ya usan issues, pull requests y revisiones. Los planes pueden publicarse como issues de GitHub con --issues, para que el trabajo llegue donde el equipo ya gestiona su backlog. Para organizaciones que quieren introducir agentes sin perder el control, es una idea práctica: la IA no reemplaza el proceso, escribe mejores elementos de trabajo que luego entran en él.
Ejecución aislada y revisión del resultado
La skill incluye también /improve execute <plan>, que despacha un ejecutor más barato en un worktree aislado, le pasa el plan y luego revisa el resultado. El flujo vuelve a pasar por los criterios de completitud, comprueba si el diff respeta el alcance y emite un veredicto: aprobar, pedir revisión o bloquear y refinar el plan.
El merge sigue estando en manos del usuario. El agente puede preparar una propuesta, pero no toma la decisión final de integrarla. Para muchos equipos, esa separación puede ser la diferencia entre usar la IA como asistente y dejar que modifique un producto sin supervisión suficiente.
Regla fija | Por qué importa |
La skill no modifica el código fuente | Reduce el riesgo durante la fase de auditoría |
Solo escribe en | Limita el alcance de sus cambios directos |
No ejecuta comandos que muten el árbol de trabajo | Evita efectos secundarios durante el análisis |
No reproduce secretos | Solo informa de la ubicación y el tipo de credencial |
Los ejecutores trabajan en worktrees desechables | Aísla los cambios y facilita la revisión |
El merge sigue en manos del usuario | Mantiene el control humano sobre el repositorio |
También existe /improve reconcile, pensado para limpiar el backlog: verificar planes que ya se ejecutaron, investigar los bloqueados, refrescar los que han derivado y retirar hallazgos corregidos por otra vía. Esta parte es menos llamativa que el comando inicial, pero puede ser una de las más útiles. Los planes de mejora envejecen rápido si el repositorio cambia cada día.
Una señal de hacia dónde van los agentes de código
shadcn/improve no es solo una herramienta curiosa para usuarios de Claude Code, Codex u otros entornos compatibles. Apunta a una tendencia más amplia: los agentes de desarrollo necesitan procesos, límites y productos intermedios. Pedir «arregla mi repo» es demasiado abierto; pedir «audita, prioriza, escribe planes verificables y deja que otro ejecute» es mucho más controlable.
Este patrón se parece a cómo trabajan los equipos humanos. Un arquitecto o tech lead normalmente no implementa cada cambio. Analiza, decide prioridades, escribe tickets, revisa propuestas y valida resultados. La IA puede aportar valor en ese papel si tiene acceso al repositorio, entiende las convenciones y produce planes que otros puedan ejecutar.
La idea también encaja con la guerra de precios en los modelos de IA. Si los modelos más capaces siguen siendo caros, las empresas necesitarán reservarlos para tareas donde su razonamiento marque la diferencia. La ejecución mecánica, los cambios repetitivos y los tests pueden moverse a modelos más baratos o a herramientas automatizadas.
No sustituye la revisión técnica, pero puede subir el nivel base
La utilidad real dependerá de cada repositorio. Un proyecto pequeño puede no necesitar una auditoría tan estructurada. Un monorepo grande, con deuda técnica, migraciones pendientes y varios equipos, puede sacarle mucho más partido. También dependerá de la calidad del modelo usado como advisor y de la disciplina del equipo al revisar los planes antes de ejecutarlos.
No hay que presentarlo como un sustituto del desarrollador senior. Puede actuar como multiplicador: encuentra duplicaciones, convierte hallazgos dispersos en planes claros, genera issues accionables y evita que un agente barato trabaje sin contexto. Para muchos equipos, eso ya es un avance real.
La programación asistida por IA avanza más allá de los prompts improvisados. El siguiente paso son flujos de trabajo donde los modelos caros razonan, los baratos ejecutan, los tests verifican y los humanos mantienen la decisión final. shadcn/improve apunta exactamente en esa dirección: menos magia, más proceso y planes que se pueden revisar de verdad.
Preguntas frecuentes
¿Qué es shadcn/improve?
Es una Agent Skill que audita un repositorio, detecta posibles mejoras y escribe planes de implementación en Markdown para que otros agentes o desarrolladores los ejecuten.
¿Cómo se instala?
El proyecto indica que puede instalarse con el comando npx skills add shadcn/improve en entornos compatibles con el formato Agent Skills.
¿Modifica el código directamente?
No. La skill escribe los planes en la carpeta plans/. La ejecución puede delegarse a otro agente en un worktree aislado, pero el merge final queda bajo el control del usuario.
¿Por qué puede reducir los costes de IA?
Porque permite reservar el modelo caro para entender y planificar, y usar modelos más baratos para ejecutar tareas bien acotadas con comandos de verificación y límites claros.